OpenRFPerm

OpenRFPerm
Header:	Resources.h		Carbon status:	Supported

Opens a file’s resource fork, when the FSpOpenResFile and HOpenResFile functions are not available.

SInt16 OpenRFPerm (
    ConstStr255Param fileName, 
    SInt16 vRefNum, 
    SInt8 permission
);

fileName: The name of the file whose resource fork is to be opened.
vRefNum: The volume reference number or directory ID for the volume or directory in which the file is located.
permission: A constant for one of the read/write permission combinations.

function result

The file reference number for the file whose resource fork it has opened. You can use this file reference number to refer to the file in other Resource Manager functions. The function also makes this file the current resource file.If the file’s resource fork is already open, the function returns the file reference number but does not make that file the current resource file.

If the function fails to open the specified file’s resource fork (because there’s no file with the given name or because there are permission problems), it returns –1 as the file reference number. Use the ResError function to determine what kind of error occurred.

Versions of system software before System 7 do not allow you to use this function to open a second access path, with write access, to a resource fork. In this case, the function returns the reference number already assigned to the file.0

DISCUSSION

You can use this function if the FSpOpenResFile function is not available. You can determine whether FSpOpenResFile is available by calling the Gestalt function with the gestaltFSAttr selector code. The HOpenResFile function allows you to specify both a directory ID and a volume reference number, and is therefore preferred if FSpOpenResFile is not available. The OpenRFPerm is an earlier versions of HOpenResFile that is still supported but is more restricted in its capabilities.

The Resource Manager reads the resource map from the resource fork for the specified file into memory. It also reads into memory every resource in the resource fork whose resPreload attribute is set.

You don’t have to call this function to open the System file’s resource fork or an application file’s resource fork. These files are opened automatically when the system and the application start up, respectively. To get the file reference number for your application, call the CurResFile function after the application starts up and before you open the resource forks for any other files.

This function checks that the information in the resource map is internally consistent. If it isn’t, ResError returns the result code mapReadErr. It’s possible to create multiple, unique, read-only access paths to a resource fork using this function; however, you should avoid doing so, to prevent inconsistencies between multiple copies of the resource map.

To open a resource fork just for block-level operations, such as copying files without reading the resource map into memory, use the File Manager function OpenRF.

If you want to open the resource fork for another application (or any resource fork other than your application’s that includes 'CODE' resources), you must bracket your calls to this function with calls to the SetResLoad function with the load parameter set to FALSE and then to TRUE. You must also avoid making intersegment calls while the other application’s resource fork is open.

SPECIAL CONSIDERATIONS

This function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.